Skip to content

Support enumDescriptions and markdownEnumDescriptions - #178

Open
Suyog241005 wants to merge 5 commits into
hyperjump-io:mainfrom
Suyog241005:support-enum-descriptions
Open

Suyog241005 wants to merge 5 commits into
hyperjump-io:mainfrom
Suyog241005:support-enum-descriptions

Conversation

@Suyog241005

@Suyog241005 Suyog241005 commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Closes #99

Supports VS Code's enumDescriptions and markdownEnumDescriptions, arrays of strings matched by position to the schema's enum.

  • Each enum value completion is documented with the description at its position. markdownEnumDescriptions is preferred, a value without a description at its position isn't documented, and extra descriptions are ignored, as in VS Code. The description follows the deprecation message and the title and description of the value.
  • Hovering an enum value shows its description after the titles and descriptions, as suggested in the issue. Hovering the property key doesn't.
  • Values are matched by their canonical JSON, the form enum is compiled to, so object values match no matter how their keys are ordered.
  • Works for plain draft 2020-12 schemas and dialects that include the vscode vocabulary.

Design

enum isn't an annotation keyword, so an annotation record didn't have the values a description is matched to. LspEvaluationPlugin now copies the compiled enum values into a schema's annotation record when an annotation keyword creates it. They never create a record on their own, so schemas with only an enum contribute nothing and the order of annotations is unchanged.

The validated value of an unknown keyword and the positions of the enum values are kept per record, because the accessors are called for every completion at a location.

A schema that applies to a location both unconditionally and as an anyOf alternative (for example $ref'd in both places) is described once: the value set gives all the annotations of a member, the location's and its own, deduplicated by identity like its other annotations.

Screenshots

Hover on a value shows the description after the title and description:

image

Hover on the key doesn't:

image

Completions for a plain enum, an anyOf alternative, and numbers:

image image

markdownEnumDescriptions preferred over enumDescriptions:

image

@Suyog241005
Suyog241005 force-pushed the support-enum-descriptions branch from 619f828 to e3f63af Compare November 2, 2026 11:25
@Suyog241005

Copy link
Copy Markdown
Contributor Author

Hi @jdesrosiers, this is ready for review. It follows the same approach as the deprecated keywords: the vscode vocabulary registers enumDescriptions and markdownEnumDescriptions, VscodeAnnotation gets accessors, and value completions and hover use them. The one design decision worth a look is in LspEvaluationPlugin: the compiled enum values are copied into a schema's annotation record so a description can be matched to its value by position.

@Suyog241005

Copy link
Copy Markdown
Contributor Author

The CI failure is in Diagnostics.test.ts, which I haven't touched. It passes locally, so I guess it's flaky.

@Suyog241005
Suyog241005 force-pushed the support-enum-descriptions branch from e3f63af to 1a66a6d Compare November 4, 2026 18:07

@jdesrosiers jdesrosiers left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I pushed a failing test. A schema that applies twice at a location should show its enum description once, the same as description. Right now completions show it twice.

@Suyog241005

Copy link
Copy Markdown
Contributor Author

I pushed a failing test. A schema that applies twice at a location should show its enum description once, the same as description. Right now completions show it twice.

Fixed. Value completions were taking the location's annotations from the evaluation and the value's from the value set, so the same schema was in both lists as different records. The value set now gives all of a member's annotations deduplicated by identity, and the provider uses that. I also added the same test for a partially typed value, which went through the evaluation path and had the same problem.

Suyog241005 and others added 5 commits November 13, 2026 22:42
VS Code's enumDescriptions describes each enum value by its position in
enum, so an annotation needs the enum values of its schema to find the
description of a value. enum isn't an annotation keyword, so its compiled
values are copied into a schema's annotation record when the record is
created, both during evaluation and when completions are built. They never
create a record on their own, so schemas with only an enum contribute
nothing and the order of annotations is unchanged.
…tions

Each enum value completion is documented with the description at its
position in the schema's enumDescriptions, preferring
markdownEnumDescriptions when there is one. A value without a description
at its position isn't documented and extra descriptions are ignored, as
in VS Code. The description follows the deprecation message and the title
and description of the value.

The description comes from the schema of the value's location, or of an
alternative that admits the value. Reading an unknown keyword validates it
against the meta-schema, which would be repeated for every completion at a
location, so the validated value is now kept per annotation record.
Hovering an enum value shows the description at its position in
enumDescriptions, or markdownEnumDescriptions, after the titles and
descriptions that apply to it. The value is matched by its canonical
JSON, the form the enum values are compiled to, so an object value is
matched no matter how its keys are ordered. Hovering a property key or
the colon of a property doesn't describe the value.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Value completions took the location's annotations from the evaluation
and the completion's from its value set. A schema that applies both
unconditionally and as an anyOf alternative was in both lists as
different records, so its enum description was shown twice.

A value set can now give all the annotations of a member, the
location's and the member's own, deduplicated by identity like its
other annotations. Value completions use those for enum descriptions.

Taking the location's annotations from the value set also means a
partially typed value is described the same as an absent one. An enum
description in a parent's `if` schema was shown only for a partially
typed value, because completions don't come from `if`; now it isn't
shown for either.
@Suyog241005
Suyog241005 force-pushed the support-enum-descriptions branch from 965266f to 12d61ae Compare November 13, 2026 17:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support enumDescriptions custom keyword

2 participants